Splunk® SOAR (On-premises)

Python Playbook API Reference for Splunk SOAR (On-premises)

The classic playbook editor will be deprecated in early 2025. Convert your classic playbooks to modern mode.
After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:

Container automation API

The Automation API allows security operations teams to develop detailed and precise automation strategies. Playbooks can serve many purposes, ranging from automating minimal investigative tasks that can speed up analysis to large-scale responses to a security breach. The following APIs are supported to leverage the capabilities of data management automation using containers.

add_artifact

Add a new artifact to the specified container. After creating an artifact, this call returns a tuple of a success flag (Boolean), any response message (string), and the artifact ID (integer).

The add_artifact API is supported from within a custom function. 

 phantom.add_artifact(container=None, raw_data=None, cef_data=None, label=None, name=None,
    severity=None, identifier=None, artifact_type=None,
    field_mapping=None, trace=False, run_automation=False)
Parameter Required? Description
container Optional The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
raw_data Required The raw artifact data is stored as-is and is accessible from the artifacts. You can also use an empty dictionary.
cef_data Required The Common Event Format (CEF) representation of the original data. You can also use an empty dictionary.
label Required The label expressing the class of artifact. For example, event or netflow.
name Required The name of the artifact.
severity Required Supported values are high, medium, low, or the name of any active severity on the system.
identifier Required The source data identifier for the artifact. Generally this is a unique ID from a data source. A value of None generates a GUID for the source data identifier.
artifact_type Required The type of the artifact, such as host or network.
field_mapping Optional If CEF field names are not specific enough, use this parameter to specify the contains type for the field. For example, if you add a playbook with an artifact that has a CEF field named user_hash, this parameter can help convey to the platform that user_hash is a hash type of field that can then be used to show contextual actions.
trace Optional Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.
run_automation Optional Default is False. If set to True, the parameter causes active playbooks to run when new artifacts are added to the container.

This sample uses the phantom.add_artifact() API. 

import phantom.rules as phantom
import json
import uuid

def on_start(container):

    artifacts = phantom.collect(container, 'artifacts:*', scope='all')
    phantom.debug(artifacts)

    raw = {}
    cef = {}
    cef['sourceAddress'] = '1.1.1.1'

    success, message, artifact_id = phantom.add_artifact(
        container=container, raw_data=raw, cef_data=cef, label='netflow',
        name='test_event', severity='high',
        identifier=None,
        artifact_type='network')

    phantom.debug('artifact added as id:'+str(artifact_id))

    artifacts = phantom.collect(container, 'artifacts:*', scope='all')
    phantom.debug(artifacts)

    # optionally user can specify a type for custom CEF fields.
    cef['foo'] = 'c8e5728b05c3ac46212c33535b65f183'
    field_mapping = {}
    field_mapping['foo'] = ['md5']

    success, message, artifact_id= phantom.add_artifact(
        container=container, raw_data=raw, cef_data=cef, label='netflow',
        name='test_event', severity='high',
        identifier=None,
        artifact_type='network',
        field_mapping=field_mapping)

    phantom.debug('artifact added as id:'+str(artifact_id))

    return


def on_finish(container, summary):

    return

The output of the playbook in the debugger shows the following results: 

Thu May 05 2016 14:03:42 GMT-0700 (PDT): Starting playbook '2498' testing on 'incident' id: '79'...
Thu May 05 2016 14:03:42 GMT-0700 (PDT): calling on_start(): on incident 'test_incident', id: 79.
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=False
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect(): will be limited to return 100 rows by default. To override, please provide limit parameter. 0 implies no limit
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect():  called with datapath 'artifacts:*', scope='all' and limit=100. Found 0 TOTAL artifacts
Thu May 05 2016 14:03:42 GMT-0700 (PDT):
[]
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.add_artifact() called
Thu May 05 2016 14:03:42 GMT-0700 (PDT): artifact added as id:122
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=False
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect(): will be limited to return 100 rows by default. To override, please provide limit parameter. 0 implies no limit
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect():  called with datapath 'artifacts:*', scope='all' and limit=100. Found 1 TOTAL artifacts
Thu May 05 2016 14:03:43 GMT-0700 (PDT):
[
    {
        "create_time": 1462482222615,
        "id": 122,
        "severity": "high",
        "label": "netflow",
        "version": 1,
        "type": "network",
        "owner_id": 0,
        "cef": {
            "sourceAddress": "1.1.1.1"
        },
        "update_time": 1462482222615,
        "hash": "4cb608956567e4a95784382de5f81c1b",
        "description": "",
        "tags": [],
        "cef_types": {},
        "start_time": 1462482222615,
        "container_id": 79,
        "kill_chain": "",
        "playbook_run_id": 25,
        "data": {},
        "name": "test_event",
        "ingest_app_id": 0,
        "source_data_identifier": "0617e876-7ca1-407d-bab4-b5c3acf644f3",
        "end_time": 0
    }
]
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.add_artifact() called
Thu May 05 2016 14:03:43 GMT-0700 (PDT): artifact added as id:123
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=False
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect(): will be limited to return 100 rows by default. To override, please provide limit parameter. 0 implies no limit
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect():  called with datapath 'artifacts:*', scope='all' and limit=100. Found 2 TOTAL artifacts
Thu May 05 2016 14:03:43 GMT-0700 (PDT):
[
    {
        "create_time": 1462482222615,
        "id": 122,
        "severity": "high",
        "label": "netflow",
        "version": 1,
        "type": "network",
        "owner_id": 0,
        "cef": {
            "sourceAddress": "1.1.1.1"
        },
        "update_time": 1462482222615,
        "hash": "4cb608956567e4a95784382de5f81c1b",
        "description": "",
        "tags": [],
        "cef_types": {},
        "start_time": 1462482222615,
        "container_id": 79,
        "kill_chain": "",
        "playbook_run_id": 25,
        "data": {},
        "name": "test_event",
        "ingest_app_id": 0,
        "source_data_identifier": "0617e876-7ca1-407d-bab4-b5c3acf644f3",
        "end_time": 0
    },
    {
        "create_time": 1462482223566,
        "id": 123,
        "severity": "high",
        "label": "netflow",
        "version": 1,
        "type": "network",
        "owner_id": 0,
        "cef": {
            "foo": "c8e5728b05c3ac46212c33535b65f183",
            "sourceAddress": "1.1.1.1"
        },
        "update_time": 1462482223566,
        "hash": "03134c15c2df2f7417f3ce360ce75d87",
        "description": "",
        "tags": [],
        "cef_types": {
            "foo": [
                "md5"
            ]
        },
        "start_time": 1462482223566,
        "container_id": 79,
        "kill_chain": "",
        "playbook_run_id": 25,
        "data": {},
        "name": "test_event",
        "ingest_app_id": 0,
        "source_data_identifier": "8dc4e4f8-0d81-4c64-8685-4742bd1d7bce",
        "end_time": 0
    }
]
Thu May 05 2016 14:03:43 GMT-0700 (PDT): No actions were executed
Thu May 05 2016 14:03:43 GMT-0700 (PDT): calling on_finish()
Thu May 05 2016 14:03:43 GMT-0700 (PDT):
Playbook '2498 (id: 58)' executed (playbook_run_id: 25) on incident 'test_incident'(id: 79).
Playbook execution status is:'success'
	No actions were executed for this playbook and 'incident'
Thu May 05 2016 14:03:43 GMT-0700 (PDT): {"message":"No actions were executed","playbook_run_id":25,"result":[],"status":"success"}

When the playbook calls this API, the newly added artifact is not accessible to this instance of the playbook run through the phantom.collect() API id scope='new'. The previous sample uses scope='all' in the phantom.collect() call to get all the artifacts including the one that was added to the container.

add_note

Use the add_note API to add a note of the specified type to the container. On completion it returns a tuple of a success flag, any response messages, and the note ID. 

phantom.add_note(container=None, note_type=None, note_format=markdown, trace=False)

The add_note API is supported from within a custom function.

Parameter Required? Type Description
container Optional Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
note_type Optional String The type of note you want to create. Valid options are "general", "artifact", or "task". For "artifact" or "task" types you must supply the artifact_id or task_id as additional parameters.
note_format Optional String The format of the note. Valid options are HTML or markdown. If the format is not provided, HTML is the default.
artifact_id Dependent Integer ID of the artifact for which you want notes.
task_id Dependent Integer ID of the task for which you want notes.
title Optional String Title for the note.
content Optional String Content for the note. The content of a note can include a limited set of HTML and Markdown. See Using HTML and Markdown in notes in the manual for a list of what is and what is not supported.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.add_note API. 

import phantom.rules as phantom

def on_start(container):

      phantom.debug('phantom.add_note')

      success, message, note_id = phantom.add_note(container=container, note_type='general', title='This is a title.', content='This is the note body.')

      phantom.debug('phantom.add_note results: success {}, message {}, note_id {}'\
                    .format(success, message, note_id))

add_tags

Use the add_tags API to add tags to a container. On completion, the call returns a success flag and any response messages.

The add_tags API is supported from within a custom function. 

phantom.add_tags(container=None, tags=None, trace=False)
Parameter Required? Type Description
container Optional Integer or Dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
tags Required String(s) The tags to be added.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.add_tags API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.add_tags start')

    success, message = phantom.add_tags(tags=['tag1', 'tag2'])

    phantom.debug(
        'phantom.add_tags results: success: {}, message: {}'\
        .format(success, message)
    )

    return

add_task

Use the add_task API to add a task to a container. It returns a success flag, a success or error message, and the ID of the created task. The add_task API is supported from within a custom function. 

phantom.add_task(container=None, name=None, owner=None, role=None, trace=False)
Parameter Required? Type Description
container Required Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object.
name Optional String Name of the task to create.
owner Optional Integer or string Identifier you can associate with the task.
role Optional Integer or string Identifier for the role to associate with the task.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.add_task() API. 

import phantom.rules as phantom
        
def on_start(container):

        phantom.debug('phantom.add_task')

        success, message, task_id = phantom.add_task(container=container, name='task name')

        phantom.debug('phantom.add_task results: success {}, message {}, task_id {}'\
                      .format(success, message, task_id))

add_workbook

Use the add_workbook API to add a workbook to a container. This API returns a two-tuple of a success flag and a message. The success flag is set to true if the workbook was successfully added, otherwise it is set to false. The message originates from the HTTP response from your web server.

The add_workbook API is supported from within a custom function. 

def add_workbook(container=None, workbook_id=None, trace=False)
Parameter Required? Type Description
container Yes Dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
workbook_id Yes Integer The ID of the workbook to be added.
trace No Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.add_workbook API. 

import phantom.rules as phantom
def on_start(container):
    phantom.debug('phantom.add_workbook start')
    phishing_workbook_id = 4
   success, message = phantom.add_tags(workbook_id=phishing_workbook_id)
   success, message = phantom.add_workbook(workbook_id=phishing_workbook_id)
    if success:
        phantom.debug('phantom.add_workbook succeeded. API message: {}'.format(message))
        # Call on_success callback
    else:
        phantom.debug('phantom.add_workbook failed. API message: {}'.format(message))
        # Call on_fail callback
    return

close

The close API allows playbooks to close the specified container by setting its status to the default status of Resolved.

The close API is supported from within a custom function.

If using the save_object() API with the auto_delete value set to True, and the container_id value specified, the stored data is deleted when this container is closed or resolved.

phantom.close(container)
Parameter Required? Type Description
container Required Dictionary A container object.

This sample uses the phantom.close() API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.close start')

    success, message = phantom.close(container)

    phantom.debug('phantom.close results: success: {}, message: {}, '\
                  .format(success, message))

    return

comment

Use the comment API to add a text comment to the container. On completion, the API returns a tuple of a success flag and any response messages.

The comment API is supported from within a custom function. 

phantom.comment(container=None, comment=None, trace=False)
Parameter Required? Type Description
container Optional Integer or Dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
comment Required String The comment to add to the container.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.comment() API. 

import phantom.rules as phantom

def on_start(container):

    success, message = phantom.comment(comment='Example comment.')

    phantom.debug(
        'phantom.comment results: success: {}, message: {}' \
        .format(success, message)
    )

    return

create_container

Use the create_container API to create a new container. It returns a tuple of a success flag, any response message, and the numeric ID of the created container. If no container was created, the ID returned is None. Once a container is created, it is possible to retrieve container data using get_container by passing the created container_id.

The create_container API is supported from within a custom function. 

phantom.create_container(name=None, label=None, container_type='default', 
    template=None, trace=False, tenant_id=1)
Parameter Required? Type Description
name Required String The name of the case.
label Required String The label of the case.
container_type Optional String The type of container to create, either default or case.
template Optional Integer or String Applies to containers of type case, and indicates the template to use on creation. If the container type is case and no template is provided, the default template is used. If no default template is set, an error is returned.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.
tenant_id Optional Integer or String The tenant ID as per the /rest/tenant API. This field is required if multi-tenancy is enabled.

This sample uses the phantom.create_container() API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.create_container start')

    success, message, container_id = phantom.create_container(name='Example Name',
                                                              label='Example Label',
                                                              container_type='case')

    phantom.debug(
        'phantom.create_container results: success: {}, message: {}, container_id: {}'\
        .format(success, message, container_id)
    )

    return

delete_artifact

The delete_artifact API allows artifacts to be deleted as identified by an artifact ID. On completion, this API returns a Boolean value indicating whether the operation was successful.

Prior to Splunk Phantom 3.0.x, only manually created artifacts were allowed to be edited or deleted. Splunk Phantom 3.0.x and later does not have this restriction, but requires that the user, either default or automation, have the delete container permission.

The delete_artifact API is supported from within a custom function. 

phantom.delete_artifact(artifact_id=None)
Parameter Required? Type Description
artifact_id Required Integer The numerical ID of the artifact to be removed.

This sample uses the phantom.delete_artifact API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.delete_artifact start')

    success = phantom.delete_artifact(artifact_id=1)

    phantom.debug('phantom.delete_artifact results: success: {} '\
                  .format(success))

    return

delete_pin

The delete_pin API is used to delete an existing pin. On completion, this API returns a success flag and a message.

The delete_pin API is supported from within a custom function. 

phantom.delete_pin(pin_id=None)
Parameter Required? Type Description
pin_id Required Integer The ID of the pin to be deleted.

Example usage to delete a pin. 

def on_start(container):

    phantom.debug('phantom.delete_pin start')

    success, message = phantom.delete_pin(pin_id=3)

    phantom.debug(
        'phantom.delete_pin results:'\
        'success: {}, message: {}'.format(success, message)
    )

    return

get_notes

The get_notes API is used to get all the notes for the requested object, either a container, a task, or an artifact. On completion, this API returns the requested notes.

The get_notes API is supported from within a custom function. 

phantom.get_notes(container=None, artifact_id=None, task_id=None, trace=False)
Parameter Required? Type Description
container Optional Integer or Dictionary The container to act on. This container can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
artifact_id Optional Integer ID of the artifact you want notes for.
task_id Optional Integer ID of the task you want notes for.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.get_notes() API.

Example: 

import phantom.rules as phantom
    
def on_start(container):
    
      phantom.debug('phantom.get_notes')
    
      for note in phantom.get_notes(container=container):
              phantom.debug('phantom.get_notes results: success {}, message {}, data {}'\
                            .format(note['success'], note['message'], note['data']))

get_phase

Use the get_phase API to retrieve the current phase of the container. On completion, this API returns a tuple of a success flag, any response messages, the phase ID and the phase name.

The get_phase API is supported from within a custom function. 

phantom.get_phase(container=None, trace=False)
Parameter Required? Type Description
container Optional Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.get_phase() API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.get_phase start')

    success, message, phase_id, phase_name = phantom.get_phase()

    phantom.debug(
        'phantom.get_phase results: success: {}, message: {}, phase_id: {}, phase_name: {}'\
        .format(success, message, phase_id, phase_name)
    )

    return

get_tags

Use the get_tags API to retrieve the tags applied to a container. On completion, this API returns a tuple of a success flag, a response message, and a list of tags.

The get_tags API is supported from within a custom function. 

phantom.get_tags(container=None, trace=False)
Parameter Required? Type Description
container Optional Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.get_tags() API.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.get_tags start')

    success, message, tags = phantom.get_tags()

    phantom.debug(
        'phantom.get_tags results: success: {}, message: {}, tags: {}'\
        .format(success, message, tags)
    )

    return

get_tasks

Use the get_tasks API to get all the tasks associated with a container. This API returns a generator object. Each item in the generator is a dictionary containing the following keys: a boolean flag "success", a response message "message" and a dictionary "data".

The get_tasks API is supported from within a custom function. 

phantom.get_tasks(container=None, trace=False)
Parameter Required? Type Description
container Optional Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.get_tasks() API.

Example: 

import phantom.rules as phantom
        
def on_start(container):
        
      phantom.debug('phantom.get_tasks')
        
      for task in phantom.get_tasks(container=container):
              phantom.debug('phantom.get_tasks results: success {}, message {}, data {}'\
                            .format(task['success'], task['message'], task['data']))

merge

Use the merge API to add items to a case. The merge API returns a tuple of a success flag and any response messages.

The merge API is supported from within a custom function. 

 phantom.merge(case=None,
              container_id=None,
              artifact_id=None,
              ioc_field=None,
              playbook_run_id=None,
              action_run_id=None,
              vault_id=None,
              note_title=None,
              note_description=None,
              trace=False)
Parameter Required? Type Description
case Optional Integer or dictionary The case to add items to. This parameter can either be a numerical ID or a container object. If no case is provided, the currently running container is used.
container_id Optional Integer The numerical ID of a container to add. All artifacts, playbook runs, action runs, vault items, notes and comments are copied. Mapping entries are created for each item that is copied, and all copied artifacts have their in_case flag set to true on the source artifact. If the container ID has already been added to the case, an error is returned. Any playbook or action runs that are running are not copied.
artifact_id Optional Integer The numerical ID of an artifact to add. This parameter copies the artifact to the case, creates a mapping entry and sets the in_case flag to true on the source container. If the artifact ID has already been added to the case, an error is returned.
ioc_field Optional String Common Event Format (CEF) key of the indicators of compromise (IOC) to add. Requires artifact ID to be specified. Copies a specific IOC from the specified artifact. A new artifact is created in the case containing the selected IOC and a mapping entry. If the IOC and artifact pair has already been added to the case, an error is returned.
playbook_run_id Optional Integer The numerical ID of the playbook run to add. Copies the playbook run, playbook run logs and all playbook action runs to the case. Mapping entries are created for the playbook runs and action runs. If the playbook run has already been added to the case, an error is returned. Playbook runs that are 'running' cannot be added to a case.
action_run_id Optional Integer The numerical ID of an action run, which can be retrieved from an action object or by using the get_summary API, which enumerates all the actions that were executed in the playbook. This parameter copies the action run to the case and creates a mapping entry. If the action run has already been added to the case, an error is returned. Action runs that are running cannot be added to a case.
vault_id Optional int The numerical value of the vault file's ID attribute. Copies a file in the vault to the case. If the vault file has already been added, an error is returned.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.
note_title Optional String The title of the note.
note_description Optional String The description of the note.

Specify only one item to merge per phantom.merge call, except in the case of the artifact_id and ioc_field. Specifying multiple parameters to merge at once can cause unpredictable results.

This sample uses the phantom.merge API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.merge start')

    success, message = phantom.merge(artifact_id=1)

    phantom.debug('phantom.merge results: success {}, message: {}'\
                  .format(success, message))

    return

pin

Use the pin API to pin data to a container. Once complete, the API returns a tuple of a success flag, any response messages, and the pin ID.

The pin API is supported from within a custom function. 

 phantom.pin(container=None, message=None,
            data=None, pin_type=None,
            pin_style=None, truncate=True,
            name=None, trace=False)
Parameter Required? Type Description
container Optional Integer or Dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
message Optional, unless the data parameter is not provided String A message associated with the pinned data.
data Optional, unless the message parameter is not provided String The data to be pinned.
pin_type Optional String The type of pin to create. The default pin type is 'card': card, data.
pin_style Optional String The style of the pin. The default pin style type is 'grey'. Options are: transparent, grey, green, blue, violet, coral, red, pink, crimson, orange, dark orange, topaz.
truncate Optional Boolean If the message or data fields are longer than the character limit, this flag determines if the data is automatically truncated or if an error is raised. The default is truncate=True, and the flag automatically truncates the message to the allowable character limit. truncate=False raises an error and no pin is created.
name Optional String The name for the pin. If there is a name, it is unique in a container. If you try to create a named pin on a container where a pin with that name already exists, it updates that pin instead of creating a new one. This parameter lets you use the pin API to create or update a pin without needing to keep track of the pin ID.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.pin() API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.pin start')

    success, message, pin_id = phantom.pin(container=container,
                                           data='192.168.1.7',
                                           message='This is a malicious IP',
                                           pin_type='card_small',
                                           pin_style='white')

    phantom.debug('phantom.pin results: success: {}, message: {}, '\
                  'pin_id: {}'.format(success, message, pin_id))

    return

promote

The promote API is used to promote a container to a case. The promote API is supported from within a custom function. 

phantom.promote(container=None, template=None, trace=False)
Parameter Required? Type Description
container Optional Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
template Optional Integer or string Either a numerical ID or the name of the template to use for the case. If no template is provided, the default template is used. If no default is set, an error is returned.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.promote() API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.promote start')

    # success, message = phantom.promote(template='Example Template Name')

    success, message = phantom.promote()

    phantom.debug(
        'phantom.promote results: success: {}, message: {}'\
        .format(success, message)
    )

    return

remove_tags

The remove_tags API is used to remove tags from a container. Upon completion, the API returns a success flag and any response messages. The remove_tags API is supported from within a custom function. 

phantom.remove_tags(container=None, tags=None, trace=False)
Parameter Required? Type Description
container Optional Integer or Dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
tags Required String(s) A string or list of strings that contains the tags to be removed.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.remove_tags() API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.remove_tags start')

    success, message = phantom.remove_tags(tags=['tag1', 'tag2'])

    phantom.debug(
        'phantom.remove_tags results: success: {}, message: {}'\
        .format(success, message)
    )

    return

set_duetime

Use the set_duetime API to modify the due time of a container. This parameter returns a tuple of a success flag, a message if available, and the new due time.

The set_duetime API is supported from within a custom function. 

phantom.set_duetime(container=None, operation='+', minutes=None, trace=False)
Parameter Required? Type Description
container Optional Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
operation Optional String A choice of add or + or subtract -, defaults to +.
minutes Required Integer The number of minutes to add or subtract.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.set_duetime() API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_duetime start')

    success, message, new_due_time = phantom.set_duetime(minutes=180)

    phantom.debug(
        'phantom.set_duetime results: success: {}, message: {}, new_due_time: {}'
        .format(success, message, new_due_time)
    )

    return

set_label

The set_label API allows users to dynamically change the label of a container. The label must already exist in system settings to be applied to a container. Upon completion, the API returns a tuple of a success flag and any response messages.

The set_label API is supported from within a custom function. 

phantom.set_label(container=None, label=None, trace=False)
Parameter Required? Type Description
container Optional Integer or Dictionary The container to act on. It can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
label Required String A string containing the label to apply.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.set_label API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_label start')

    success, message = phantom.set_label(label='Example label')

    phantom.debug(
        'phantom.set_label results: success: {}, message: {}'\
        .format(success, message)
    )

    return

set_owner

Use the set_owner API to dynamically assign a container or task to a user or role. Upon completion, the API returns a tuple of a success flag and a message, if available.

The set_owner API is supported from within a custom function. 

phantom.set_owner(container=None, task_id=Int, user='', role='', trace=False)
Parameter Required? Type Description
container Optional Integer or dictionary The ID of the container assigned ownership. If no container is provided, the currently running container is used.
task_id Optional Integer The task ID of the task assigned ownership. If an empty string is sent, this API removes any owners from the task.
user Optional String or integer Valid username or ID assigned, or an empty string to remove assignments on the container. If you don't set a user, or you send an empty string, you remove assignments from the container.
role Optional Integer or string The name or ID of the role. If no user or role values are set or if empty strings are sent, role assignments are removed from the container or task.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.set_owner() API. 

import phantom.rules as phantom

def on_start(container):

  # assign container to user@company.com
  success, message = phantom.set_owner(container=container, user='user@company.com')
  phantom.debug(
      'phantom.set_owner results: success: {}, message: {}'
      .format(success, message)
  )

  # container unassigned, no user assigned
  success, message = phantom.set_owner(container=container, user="")
  phantom.debug(
      'phantom.set_owner results: success: {}, message: {}'
      .format(success, message)
  )
  return

set_phase

Use the set_phase API to set the current phase of the container. This parameter returns a tuple of a success flag and a message, if available.

The set_phase API is supported from within a custom function. 

phantom.set_phase(container=None, phase=None, trace=False)
Parameter Required? Type Description
container Optional Integer or Dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
phase Required String or Integer Use either a phase name or a numerical ID for the phase to apply.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

This sample uses the phantom.set_phase API.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_phase start')

    success, message = phantom.set_phase(phase='Example Phase')

    phantom.debug(
        'phantom.set_phase results: success: {}, message: {}'\
        .format(success, message)
    )

    return

set_sensitivity

Use the set_sensitivity API to dynamically change the sensitivity of a container while it is being processed. The system supports four levels of sensitivity in accordance to the US-CERT Traffic Light Protocol. The levels supported are red, amber, green, and white.

The set_sensitivity API is supported from within a custom function. 

phantom.set_sensitivity(container, sensitivity)
Parameter Required? Type Description
container Required Dictionary The current container object.
sensitivity Required String The desired sensitivity. Options include red, amber, green, and white.

set_severity

Use the set_severity API to dynamically change the severity of a container while it is being processed.

The set_severity API is supported from within a custom function. 

phantom.set_severity(container, severity)
Parameter Required? Type Description
container Required Dictionary The current container object.
severity Required String The name of your desired severity level.

set_status

Use the set_status API to update the status of a container. Returns a tuple of a success flag and a message, if available.

The set_status API is supported from within a custom function. 

phantom.set_status(container=None, status=None, trace=False)
Parameter Required? Type Description
container Optional Integer or dictionary The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
status Required String Set the status of either new, open, resolved, closed, or a custom status defined by an administrator.
trace Optional Boolean Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output.

Prior to Splunk Phantom 4.5 the statuses of Resolved and Closed were interchangeable. With customizable statuses, the statuses are no longer interchangeable. For backwards compatibility, if there is no active status named Resolved, calling this API with a value of resolved causes the set_status API to retry with a value of closed. If you depend on resolved and closed being interchangeable, call the phantom.set_status() API with status="closed" instead.

This sample uses the phantom.set_status API. 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_status start')

    success, message = phantom.set_status(status='open')

    phantom.debug(
        'phantom.set_status results: success: {}, message: {}'\
        .format(success, message)
    )

    return

update

Use the update API to make an update to a container. It returns a tuple of a success flag and any response messages.

The update API is supported from within a custom function. 

phantom.update(container, update_dict)
Parameter Required? Description
container Required The container object to be updated.
update_dict Required A JSON serializable Python dictionary which contains updates to the container. Include only the fields that you want to change.

Example usage to change the container label to email and sensitivity to red. 

update_data = { "label": "email", "sensitivity": "red" }
success, message = phantom.update(container, update_data)


Example usage to append a new tag to the container. 

current_tags = phantom.get_container(container['id'])['tags']
current_tags.append('newtag2')
update_data = { "tags" : current_tags }
success, message = phantom.update(container, update_data)

Changing the label on a container can potentially trigger automatic playbook runs on that container if there are any playbooks set to active that run on that container label. Standard automatic playbook run constraints apply, such as actions not running if the playbook had already run and there are no new artifacts, or if the container is in a closed state. You can set "run_automation": false in the JSON to block playbooks running on this update call.

Updating and reading custom field values

For information on updating and reading custom field values with the container.update API, refer to Update and read custom field values.

update_pin

Use the update_pin API to update an existing pin. Upon completion, this API returns a success flag and a message.

The update_pin API is supported from within a custom function. 

phantom.update_pin(pin_id=None, message=None, data=None, pin_type=None, pin_style=None)
Parameter Required? Type Description
pin_id Required Integer The ID of the pin to be updated.
message Optional String A new message string for the pin.
data Optional String A new data string for the pin.
pin_type Optional String A new type for the pin.
pin_style Optional String A new style for the pin.

Use named pins instead of this API to handle updating pins.

In this example, an existing pin's message and data is updated. 

def on_start(container):

    phantom.debug('phantom.update_pin start')

    success, message = phantom.update_pin(pin_id=3, message="A new message",
                                          data="Some new data")

    phantom.debug(
        'phantom.update_pin results:'\
        'success: {}, message: {}'.format(success, message)
    )

    return
Last modified on 20 September, 2024
Playbook automation API   Data management automation API

This documentation applies to the following versions of Splunk® SOAR (On-premises): 6.2.1, 6.2.2, 6.3.0, 6.3.1

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters